#850 [DOC-49] Add platform economics and fee structure analysis FIX - #920

Closes #850

What Changed

• docs/TOKENOMICS.md — full rewrite (171 → 755 lines). The previous version had
  drifted from the deployed contract (claimed the fee was "fixed", fee tiers "planned",
  burn "not implemented"). The rewrite documents, function-by-function, what
  contracts/escrow/src/lib.rs actually does:
  • Fee calculation & distribution — exact formula
    (fee = floor(amount × fee_bps / 10_000), truncation semantics), base 250 bps,
    worked stroop-level examples, per-token accrual (TokenFees) → withdraw_fees
    lifecycle, burn allocation mechanics, and conservation invariants tied to existing
    contract tests.
  • Four Mermaid fee-flow diagrams — happy path, full waterfall (tiers / late fee /
    burn / referral / multi-approver branch), dispute deposit + half-slashing flow, and
    the zero-revenue refund/cancel branches.
  • Per-party economic incentive analysis — client, freelancer, platform admin,
    referrer, oracle, relayer, plus an alignment/tension map (e.g. why 50/50 dispute
    resolutions count as a raiser loss, why referral rewards can't be farmed).
  • Sensitivity analysis of fee changes — revenue-per-GMV grids per 100 bps,
    breakeven GMV at illustrative cost levels, the disintermediation ceiling, micro-job
    rounding floor, dispute-deposit regressivity, late-fee/burn/referral-budget
    interactions, and a parameter interaction table.
  • Competitive comparison — 8-platform table (Upwork's post-2025 variable 0–15%,
    Fiverr 20% + buyer fees, Freelancer.com, Toptal, Contra, LaborX, Guru) with sources,
    dated September 2026.
  • Also: full parameter reference table, governance & safety bounds, on-chain
    auditability event map, corrected FAQ, and a "keeping this doc in sync" section.
• scripts/check-tokenomics-docs.py (new, 138 lines) — automated doc↔code
  consistency guard. Parses DEFAULT_FEE_BPS, MAX_FEE_BPS, MAX_FEE_BPS_CONFIG,
  MAX_FEE_TIERS, DEFAULT_DISPUTE_FEE, DEFAULT_ORACLE_FEE, DEFAULT_BURN_BPS,
  REFERRAL_BPS from the contract plus the frontend mirrors
  (transactions.ts FEE_BPS, fee-calculator PLATFORM_FEE_PERCENT) and asserts the doc
  quotes identical values and cites functions that still exist.
• .pre-commit-config.yaml — adds a tokenomics-docs hook (system python3,
  files: filter on the 4 coupled paths) so editing the fee logic or its frontend
  mirrors re-validates the documentation; ordinary PRs pay zero cost.
• docs/README.md — one line: updated the TOKENOMICS.md index description.

Design trade-offs:

• Updated the existing TOKENOMICS.md in place instead of adding a parallel
  ECONOMICS.md, so all doc links/index entries keep working and there is exactly one
  source of truth.
• The doc deliberately reports the contract's warts (two fee setters with different
  caps — 10% vs 100%; execute_burn being accounting rather than token destruction;
  dispute paths ignoring tiers/exemptions/burn; the orphaned src/test.rs referencing
  non-existent rebate/SLA APIs). Transparency was the issue's stated goal, and a
  stakeholder doc that hides these is worse than none. No contract behavior was changed.
• Consistency checking is a standalone script rather than a Rust test so it can span the
  contract, both frontend mirrors, and the markdown — and run without a toolchain.
• No contract or frontend code was modified: git diff --exit-code contracts/escrow/src/lib.rs passes; the entire change surface is 2 docs files, 1 new
  Python script, 1 pre-commit hook block.

Validation

• I referenced the related issue in this PR. (Closes # — insert issue number)
• Contract checks pass (soroban contract build and cargo test in
  contracts/escrow) if contract code changed. N/A — verified no contract code
  changed (empty git diff on contracts/escrow/); nothing in the test graph was
  touched. cargo/docker are unavailable in this environment, so instead the doc's
  claims were each re-verified against lib.rs source this session and enforced
  mechanically by python3 scripts/check-tokenomics-docs.py → OK (fee=250 bps,
  caps=1000/10000 bps, tiers≤10, dispute=50,000,000 stroops, oracle=20,000,000 stroops,
  referral=50 bps, burn_default=0 bps).
• Frontend checks/build pass for changed frontend files. N/A — zero frontend
  files modified (confirmed via git status).
• I included screenshots or short clips for UI changes (or noted N/A). N/A —
  no UI changes. (Rendered Mermaid diagrams view on GitHub's markdown preview of the
  changed file.)
• I verified the UI changes in the preview deployment. N/A — docs-only; no UI
  or runtime surface to verify.
• Also ran the repo's own checks: python3 scripts/check-tokenomics-docs.py (passes;
  and passes an adversarial negative test — mutating DEFAULT_FEE_BPS to 300 in a
  scratch copy produced exactly the 3 expected FAIL: lines before reverting),
  python3 scripts/check-heading-hierarchy.py (passes for all docs incl. the rewritten
  file), YAML parse of .pre-commit-config.yaml (valid, 8 hooks), and an
  anchors/relative-links audit of the new doc (none broken).

Additional Notes

• Reviewer context: every monetary figure in the doc traces to a named function in
  contracts/escrow/src/lib.rs; spot-check the "Fee Calculation and Distribution" and
  "Other Monetary Flows" sections against approve_work, resolve_single_dispute, and
  submit_verdict. The "Known Gaps and Cautions" section is a candidate seed for new
  issues — especially the update_fee (≤10%) vs update_fee_bps (≤100%) cap mismatch,
  which I'd recommend fixing in-contract rather than re-documenting here.
• Follow-ups (deliberately out of scope): unify the two fee-setter caps behind the
  24h upgrade timelock; make dispute paths tier/exemption-aware or document-by-design;
  make execute_burn call token burn() for anchored assets; delete or wire up the
  orphaned contracts/escrow/src/test.rs; replace the frontend's static 250 bps mirror
  with a get_fee_bps() read.
• Risks: competitor fee tables are point-in-time (sourced, dated Sep 2026) and need
  periodic refresh; the pre-commit hook requires python3 on PATH, consistent with the
  existing language: system hooks (cargo/npm).
• Contributor docs need no changes: the hook is transparent and the checker's failure
  messages name the drifted constant directly.